SPACE 2

home *** CD-ROM | disk | FTP | other *** search

/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / utility / 647 / on_line / on_line.doc < prev

Wrap

Text File | 1992-10-14 | 17KB | 447 lines

ON_LINE.DOC 1.0 OCT. 1992 NOTE: These programs need to be on a HARD DRIVE to run. The purpose of these programs is to provide an editable On Line manual for GFA BASIC. These programs will run in ST high & ST medium. These programs will run on ATARI ST, ATARI MEGA STe, ATARI TT computers. And on TOS 2.06 After UnArcing ON_LINE.ARC there should be 4 files. 1. ON_LINE.DOC 1.0 - This text file. 2. ON_LINE.ACC 1.0 - The On Line accessory. 3. CREATEON.PRG 1.0 - The program that initially creates the random access file ( ********.RAN ). And does other stuff also. 4. MANUAL.TXT 1.0 - The On Line manual in text file form. Quick Start - For those in the crowd that would like to get started right away. Copy ON_LINE.ACC to directory C:\ Copy CREATEON.PRG to your hard drive (anywhere). Run CREATEON.PRG You may be able to figure it out from there. Slow but sure start - Read this file. CREATEON.PRG - Pull down menu. Desk Me - CreateOn - a note about who wrote the programs. Random Me - Create Random Access File - the random access file is made up of pages (records). The size of the page is up to the user - you. The size of the page is configurable from 15 to 79 characters horizontally. 5 to 20 characters vertically. And there may be 100 to 1000 pages in the random access file. The random access file size will be shown and then the user will be given a choice to create the file or not. If there is not enough space on the hard drive to create the file an alert box will let the user know. The random access file can be anywhere on the hard drive and can be named anything. If the extension .RAN is left off it will be added for the user. The file C:\ON_LINE.DAT will also be created at this time. This file contains data that ON_LINE.ACC will use. ON_LINE.DAT must stay in the root directory on C:\ drive. Also if at anytime the user wants to mess around with these files make a copy and mess with the copy. It is almost guaranteed that if these files are altered the programs will not run correctly. Recommended beginning random access file size - 79 characters horizontal, 20 characters vertical, 300 pages. Random Me - Add to .RAN from a Text File - select a text file and the pages (records) there in will be added to the random access file. Duplicates will not be added. MANUAL.TXT should be the first text file added to the random access file. The pages (records) in the Text file must be separated by "*****" At least 5 asterisk in a row. Look at MANUAL.TXT for a better idea. Random Me - Create a Text File from .RAN - this selection will generate a text file from the random access file. The pages (records) will be alphabetically sorted. This is a good way to make a back up of the random access file. Also this is the method that will be used to transfer an On Line manual when new versions of these programs are released. Random Me - Append a Text File from .RAN - an existing text file will be appended from the random access file. The pages (records) added will be in alphabetical order. Random Me - Absolute - .RAN to Text File - a text file will be generated from the random access file sequentially. It is possible for pages (records) to get lost in the random access file. This is a way to recover that information. The pages will not be in alphabetical order. Random Me - Call ON_LINE.PRG - ON_LINE.ACC may be renamed to run as a program. If there is enough free RAM and if ON_LINE.PRG is in the same directory as CREATEON.PRG ON_LINE.PRG may be run from CREATEON.PRG Random Me - Quit - quit the program. ON_LINE.ACC - the On Line manual interface, runs in 44 K. The options at the bottom of the screen are selected by pressing the outlined letter in the respective word or clicking on the word. For example to select Add - press "a" or "A" on the keyboard or click directly on the word "Add". Add - use this option to add a new page to the random access file. The index of the page must be in the first line and the first 15 characters. An addition might look like this. characters 123456789... 1. PRINT 2. 3. In the example the index is the word PRINT. List an existing page for another example. Modify - this is the way to modify an existing page. Select a page to modify from the list of pages. Then modify it. Delete - delete a page from the random access file. Select a page to delete from the list of pages. The page will be shown on the screen, then the user will have the option to delete. Be sure because once it's gone it's history. List - display a page to the screen. ON_LINE.ACC is specifically designed to be called from the pull down menu in GFA BASIC accessible by clicking on  (the ATARI symbol) at the top left of the editor screen in GFA BASIC. This action leads us to the output screen with a pull down menu at the top. If the user Lists a page to the screen and then Quits the page will be left on the output screen because ON_LINE.ACC will not send a redraw to the program that called it. So what was the exact syntax of that command ? The paper manual is on the bookshelf. Call ON_LINE.ACC, List the page to the screen, Quit, go back to the editor. Now - the user can toggle back and forth (if needed) from the editor to the List using the Esc key. The List is still there. ⇧ (up arrow) - the list of pages can get pretty long so this is the way to move around in the list. Move alphabetically backward. Also the list of pages only shows the first 8 characters of the index. 15 characters are used by the program internally for comparisons. ⇩ (down arrow) - move alphabetically forward. Quit - Return to the parent program (usually GFA BASIC). The file ON_LINE.DAT maybe updated at this time - if any significant changes have been made. So if the user turns off power to the computer before Quit - significant changes maybe lost. Significant changes would be - an Add, a Delete, a Modify that changes any characters with in the first 15 characters of the first line of a record. LF: #### of #### ###.## % - yes that's a mouth full. Lets say there are 100 pages in the random access file and 10 to them are full. The load factor line looks like this. LF: 10 of 100 10.00 % Get the idea. The load factor tells the user how full the random access file is. If the load factor gets to be 80% or more create a new random access file with more pages and transfer the manual using a text file. CAUTION - a word of caution. Although these programs have been used and tested the user may want to back up the hard drive. This is a good idea whether or not the user uses these programs. Credit - these programs were written in the United States using GFA BASIC and DevpacST2. Assembly language was used to speed up some of the routines - not that GFA is slow but assembly is faster. Share Ware - Support Share Ware and Public Domain programmers. It's so easy to go about our business and forget that someone spent hours designing a program for us to use. They could have kept it to themselves. Often the Share Ware & Public Domain programmers receive very little thanks - Seriously. Don't count on some other user to send in a check or thank you note. Every other person is thinking the same thing you are - someone else will do it. For those users that do register I'll send you four assembly routines on disk. Routine 1 - pass in a horizontal (x) pixel number. The routine will return the text row that the pixel is located in. Routine 2 - similar to Routine 1 except this one works with the vertical (y) pixel number. By using both of the above routines we can tell which letter on the screen the user clicked on. Routine 3 - pass in a horizontal (x) text row. The routine will return the exact pixel so that TEXT can be placed on the screen in the same position as PRINT. Routine 4 - similar to routine 3 except works vertically (y). Routines 3 and 4 work together to give us a LOCATE command for the TEXT command. These routines are written in 100% assembly code using DevpacST2 and run at least 4 times faster than their respective fully optimized GFA BASIC counter parts. I'll show you how to use them with GFA BASIC 2.0, and GFA BASIC 3.0 These routines are compatible with ST high and ST medium. Also an assembler is not required to to use these routines And how about a tutorial and programming example on the subject of using random access files and hashed random access files in GFA BASIC. Bugs - yea, there are probably some still in there. If you run into one let me know even if you aren't registered - you will be doing everyone a favor. The editor - The on line editor is not the best I know. Some users may want to use a favorite word processor for major editing of a text file and then add the text file to the random access file. But to get the most out of the existing editor read up on the FORM INPUT n AS s$ command. There is a rumor that an integrated word processor is in the works. These programs are Share Ware: $15 CHARLES H. HARVEY P.O. BOX 701 LOUISVILLE, CO 80027 On Genie: C.HARVEY9 Homework - yea, you heard right HOMEWORK. For this Homework you will be required to write FUNCTIONs ENDFUNC and PROCEDUREs RETURN in GFA BASIC. Procedures and Functions are very powerful tools that we can use to write efficient programs. Once we know the concepts we can then decide whether to use them or not. If we don't know about the concepts or chose to not learn them then we don't really have a choice of how to do things. Procedures preform a task. They can change the values of our variables if we allow them to or not. A good example of a procedure is a routine that sorts an array. example - @sort(any_string_array$()) PROCEDURE sort(VAR an_array$()) ' ' some clever code ' RETURN In the first line of the example we call the Procedure sort and we pass it the name of ANY string array we have previously dimension. This is very powerful. We can use one section of code to sort any number of arrays in a program. We don't have to write 10 similar routines to sort 10 different string arrays. This saves on program size. Also it gives us the ability to write a section of code and then reuse it again in other programs. In the first line of the procedure the word VAR gives the procedure sort permission to change the values of the array passed to the procedure. Arrays must be passed this way - whether we want to give the procedure permission to change the values of the array or not. When the computer gets to the RETURN at the end of the procedure - program execution will continue with the line following the procedure call. Think of how GFA is set up. For instance the Sort commands, these are procedures written in assembly that we can all use. Every time we write a program we don't have to rewrite those sort commands - they are already done for us. Pretty useful. But many of the commands in GFA are functions. Functions are similar to Procedures in that we pass variables to them. And they also preform a task. But there are at least 2 big differences between procedures and functions. Functions are designed to return one value, and functions may have more than one RETURN. Lets get right to an example. The command MIN() in GFA is a function. We pass it a number of values (lets say 2) and it returns a value - the lowest value. Lets write our own @min() function. PRINT @min(10,20) FOR x=1 TO @min(10,number&) NEXT x Above are only 2 of the many ways to call the function min() FUNCTION min(value1,value2) IF value1 <= value2 THEN RETURN value1 ELSE RETURN value2 ENDIF ENDFUNC More than one return - this gives us a lot of room. So we can write our own commands using the existing base of commands in GFA. But first there are two concepts that we need to discuss in detail. PROCEDURE some_thing LOCAL number,string$ LOCAL flag! ' ' some code ' RETURN The variables - number, string$, and flag! are local variables. They are local to the PROCEDURE some_thing. sum=13 a=1 b=2 c=3 d=@add(a,b,c) ' FUNCTION add(x,y,z) LOCAL sum ' sum=x+y+z RETURN sum ENDFUNC In this example the value of the sum on the first line will not change when the LOCAL sum value becomes 6 because the sum inside the FUNCTION is LOCAL to the FUNCTION add. If variables are not LOCAL they are by default GLOBAL. Ok. VAR - gives the procedure permission to change the value of a variable. a=2 b=4 c=7 sum=0 ' @example(a,b,c,sum) ' PROCEDURE example(x,y,z,the_sum) the_sum=x+y+z RETURN In the above example we want to change the value of sum but it's not going to happen because we did not use VAR. This is a difficult error to find. Everything looks great, the value is being changed right there in the PROCEDURE. Watch out for that one. a=2 b=4 c=7 sum=0 ' @example(a,b,c,sum) ' PROCEDURE example(x,y,z,VAR the_sum) the_sum=x+y+z RETURN Now the PROCEDURE will work. OK. The homework is: 1. Write a FUNCTION that accepts 5 numbers and RETURNs the MIN value. The call might look like this. PRINT @min(a,b,c,d,e) 2. Write a FUNCTION similar to #1 but RETURNs the max value. 3. Write a FUNCTION that RETURNs the absolute value of a number. The call might look like this. PRINT @absolute_value(number) 4. Write a FUNCTION that inserts a string into a second string without overwriting any characters in the second string. Also the user gives the position in the second string that the first string will be inserted. The call might look like this. PRINT @insert$("new_part","insert_in_this_string",4) 5. Write a FUNCTION similar to UPPER$("characters"). In other words write a FUNCTION that changes lower case letters in a string to upper case letters. The call might look like this. PRINT @upper_case("any characters &#@=!*!(") 6. Write a FUNCTION that changes upper case letters in a string to lower case letters. The call might look like this. PRINT @lower_case("Any Characters &#@=!*!(") When doing the homework don't cheat by using the obvious basic command. Registered Users - go ahead and do the homework - send it to me in the mail. I'll grade it and let you know how you did. If any problems in the assignment were missed I'll give you the solutions. These are good practice but we would not want to use 1-3,5 in a real program because they would be slower then their GFA BASIC counter parts. Sorry, no extra credit this time. Atari, ST, are copyrights of Atari Corporation. All other products mentioned are copyright and/or trademark of their respective holders.